home *** CD-ROM | disk | FTP | other *** search
/ Aminet 43 / Aminet 43 (2001)(GTI - Schatztruhe)[!][Jun 2001].iso / Aminet / text / edit / rexx-mode1_1.lha / rexx-mode / rexx-mode.doc < prev    next >
Lisp/Scheme  |  2001-04-29  |  11KB  |  363 lines
  1.  
  2.                rexx-mode  V1.1
  3.                ~~~~~~~~~~~~~~~
  4.                    
  5.         Copyright (C) 1993 by Anders Lindgren.
  6.         Copyright (C) 2000 by James S Perrin
  7.                    
  8.           This file is NOT part of GNU Emacs (yet).
  9.                    
  10.                    
  11.                    
  12.                  DISTRIBUTION
  13.  
  14.     rexx-mode is free software; you can redistribute it and/or modify
  15.     it under the terms of the GNU General Public License as published 
  16.     by the Free Software Foundation; either version 1, or (at your 
  17.     option) any later version.
  18.  
  19.     GNU Emacs is distributed in the hope that it will be useful,
  20.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  21.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22.     GNU General Public License for more details.
  23.  
  24.     You should have received a copy of the GNU General Public
  25.     License along with GNU Emacs; see the file COPYING.  If not,
  26.     write to the Free Software Foundation, 675 Mass Ave, Cambridge,
  27.     MA 02139, USA.
  28.  
  29.  
  30.                    ORIGINAL AUTHOR
  31.           Anders Lindgren, d91ali@csd.uu.se
  32.                    
  33.                Abbrevationtable due to:
  34.         Johan Bergkvist, nv91-jbe@nada.kth.se
  35.  
  36.                   Font-Locking and current Maintainer:
  37.                 James S Perrin, james.perrin@man.ac.uk
  38.  
  39.  
  40.                  INTRODUCTION
  41.  
  42.     The rexx-mode is a package contains an edit mode for the
  43.     REXX language, called rexx-mode, and a source level debugging
  44.     mode, called rexx-debug (or rxdb-mode for short) for the
  45.     GNU Emacs editor.
  46.  
  47.     The following files is part of the distribution:
  48.  
  49.     rexx-mode.doc        This file
  50.     rexx-mode.el        The elisp code for rexx-mode.
  51.     rexx-debug.el        The elisp code for the debugger.
  52.     comint.el        General purpose process communication
  53.                     module by Olin Shivers.
  54.     *.elc            Byte-compiled versions of the above.
  55.     
  56.     readme.amiga        Some details concerning a bug in
  57.                 the Amigaport V1.26 of GNUEmacs.
  58.     rxnq/rxnq        A hack to fix the above mentioned bug.
  59.     rxnq/rxnq.c        Sourcecode in C for rxnq.
  60.     
  61.  
  62.                 HOW TO INSTALL
  63.  
  64.     In order to use the rexx mode and the debugger they have
  65.     to be loaded into Emacs. This can manually be done
  66.     by M-x load-library RET rexx-mode RET. Although this
  67.     is rather cumbersome. A better way is to autoload them,
  68.     i.e. emacs loads them when they are needed.
  69.  
  70.     Emacs can also recognize certain types of files and
  71.     start the correct mode accordigly.
  72.  
  73.     The script below will recognize .rexx, .elx, .ncomm and .cpr
  74.     files as REXX-files. If you would like others to be recognized,
  75.     create additional (cons ...) lines. Please insert the script
  76.     to your ~/.emacs file.
  77.  
  78.     See also the parts on custimation below.
  79.  
  80.     --- cut here --- cut here --- cut here --- cut here ---
  81.  
  82. (autoload 'rexx-mode  "rexx-mode"  "REXX mode" t)
  83. (autoload 'rexx-debug "rexx-debug" "REXX source level debugger" t)
  84. (setq auto-mode-alist
  85.       (append
  86.        (list (cons "\\.rexx$"  'rexx-mode)
  87.          (cons "\\.elx$"   'rexx-mode)
  88.          (cons "\\.ncomm$" 'rexx-mode)
  89.          (cons "\\.cpr$"   'rexx-mode)
  90.          )
  91.        auto-mode-alist))
  92.  
  93.     --- cut here --- cut here --- cut here --- cut here ---
  94.  
  95.  
  96.                   EDIT MODE
  97.  
  98.     The edit mode knows the indentations rules which applies to
  99.     REXX programs, and tries to indent the lines accoringly. It is
  100.     capable of recognizing DO-blocks, SELECT-blocks, IF-THEN-ELSE
  101.     statements etc. It also recognizes comments and strings.
  102.  
  103.     To indent the line, execute the funciton rexx-indent-command,
  104.     which is normally bound to TAB. It indents line line (or
  105.     inserts a TAB depending on the cursor position and the
  106.     variable rexx-tab-always-indent.)
  107.  
  108.     The standard GNU Emacs commands, such as indent-region 
  109.     work properly in rexx-mode.
  110.  
  111.               CUSTOMIZATION OF REXX-MODE
  112.  
  113.     rexx-mode follows the Emacs tradition of being as customizable
  114.     as possible. The following variables directs the indentation:
  115.  
  116.     rexx-indent:
  117.         The basic indentation for do-blocks.
  118.  
  119.     rexx-end-indent: 
  120.         The relative offset of the "end" statement.
  121.         0 places it in the same column as the statements of
  122.         the block. Setting it to the same value as
  123.         rexx-indent places the "end" under the do-line.
  124.  
  125.     rexx-cont-indent:
  126.         The indention for lines following "then", 
  127.         "else" and "," (continued) lines.
  128.  
  129.     rexx-tab-always-indent:
  130.         Non-nil means TAB in REXX mode should always reindent
  131.         the current line, regardless of where in the line the
  132.         point is when the TAB command is used.
  133.  
  134.     
  135.     The variable rexx-indent set the basic indentation. Setting
  136.     it to 4 results in the following indentation:
  137.  
  138.         DO
  139.             SAY 'foo'
  140.             ...
  141.  
  142.     while setting it to 8 (which is the default) results in:
  143.  
  144.         DO
  145.             SAY 'foo'
  146.             ...
  147.  
  148.     The variable rexx-cont-indent indents IF-THEN-ELSE statements
  149.     and continued lines. It is strongly recomended to set it
  150.     to the same value as rexx-indent.
  151.  
  152.     The rexx-end-indent controls the placement of the END. If it
  153.     contains 0 the end is placed in the same column as the block,
  154.     for example:
  155.  
  156.         DO
  157.             SAY 'foo'
  158.             END
  159.  
  160.     A positive value will move it to the left, by setting it to the
  161.     same value as rexx-indent the end is aligned with the DO, as
  162.     shown below:
  163.  
  164.         DO
  165.             SAY 'foo'
  166.         END
  167.  
  168.  
  169.     The return key ought to be redefined to either 
  170.     rexx-newline-and-indent, or rexx-indent-newline-indent.
  171.     The latter is prefered if the indentation has been configurated
  172.     to place the END under the corresponding DO or SELECT-statement.
  173.     It indents the current line before creating a new. If a non-
  174.     standard indentation is wanted, press C-q RET TAB to create
  175.     a new line without indentating the current.
  176.  
  177.     The "normal" newline-and-indent command is not recomended since
  178.     it doesn't expand abbrevs.
  179.  
  180.                 FONT-LOCK MODE
  181.  
  182.     Font-locking recognises strings and comments by syntax and
  183.     reserved words and functions by keyword lists, they will be
  184.     highlighted using suitable colours. The amount of highlighting
  185.     performed can be controlled with font-lock-maximium-decoration
  186.     variable. Set to 1 for just strings and comments, 2 keywords and
  187.     3 or t for functions.
  188.  
  189.  
  190.                  ABBREV MODE
  191.  
  192.     The editing mode contains an abbrevation table consisting of
  193.     all the keywords of REXX. When active it will automatically
  194.     convert all keywords into upper case when typed. 
  195.  
  196.     Abbrev-mode is turned on by M-x abbrev-mode, or by calling
  197.     (abbrev-mode 1) from lisp, for example from a hook.
  198.  
  199.  
  200.                   DEBUG MODE
  201.  
  202.     The debug mode is a simple fontend to the normal rexx debugger
  203.     Currently, the ONLY thing it does is to parse the output
  204.     for line-numbers. If one is found, an arrow is placed on the
  205.     corresponding line in the window containing the source.
  206.  
  207.     The rexx-debug mode is called by the function rexx-debug, which
  208.     is bound to C-c C-c in rexx-mode. It will prompt you for
  209.     the name of the file (press return to use the current buffer)
  210.     and the arguments to send to the script.
  211.  
  212.     The debug-mode is built using comint.el by Olin Shivers which
  213.     contains full history and other command line features.
  214.  
  215.     The following keys can be used in rexx-debug mode.
  216.  
  217.     m-p                    Cycle backwards in input history.
  218.     m-n                        Cycle forwards.
  219.     m-s                Previous similar input.
  220.     c-m-r             Search backwards in input history.
  221.     return            Send input to REXX.
  222.     c-a                     Beginning of line; skip prompt.    
  223.     c-d                  Delete char unless at end of buff. 
  224.     c-l            Refresh
  225.     c-c c-u                   Kill input.
  226.     c-c c-w                   Backward kill word.
  227.     c-c c-c               Interrupt subjob.
  228.     c-c c-z                   Stop subjob.
  229.     c-c c-\                   Quit subjob.
  230.     c-c c-o                   Delete last batch of process output.
  231.     c-c c-r                   Show last batch of process output.
  232.  
  233.     Suggestions of additions to this mode is appreciated.
  234.  
  235.  
  236.            CUSTOMIZATION OF THE DEBUG MODE
  237.  
  238.     The rexx-debug mode contains the following variable:
  239.  
  240.     rxdb-command-name
  241.         The name of the REXX interpretator in the current system.
  242.  
  243.  
  244.                 HOOKS
  245.  
  246.     The normal way to configureate a mode under Emacs is to create
  247.     a so called hook, which is called when a mode is started. This
  248.     is way better then to setq all varaibles on startup. For example,
  249.     you never have to look up the name of the keymap, use 
  250.     local-set-key instead. Hooks is normally placed in ~/.emacs,
  251.     or in other files loaded at startup.
  252.  
  253.  
  254.     The following hooks are called:
  255.  
  256.     rexx-mode-hook    on entry to rexx-mode.
  257.  
  258.     rxdb-mode-hook      when entering rexx-debug mode (rxdb-mode).
  259.     
  260.     comint-mode-hook  is also called before the above, as it is by
  261.               all modes which uses comint. (i.e. Don't put
  262.               any REXX-specific stuff here.)
  263.  
  264.  
  265.     A hook looks like:
  266.  
  267.     (setq some-hook '(lambda ()
  268.                ;; statements to be executed when mode started.
  269.                ))
  270.     
  271.     [ Technically, the variable some-hook is assigned to a nameless
  272.     function, indicated by the (lambda () ...), which is executed when
  273.     the mode is stared. ]
  274.  
  275.  
  276.     Example 1:
  277.     (setq rexx-mode-hook '(lambda ()
  278.             (setq rexx-indent 4)
  279.             (setq rexx-end-indent 4)
  280.             (setq rexx-cont-indent 4)
  281.             (local-set-key "\C-m" 'rexx-indent-newline-indent)
  282.             (abbrev-mode 1)
  283.             ))
  284.  
  285.     will make the END aligned with the DO/SELECT. It will indent
  286.     blocks and IF-statenents four steps and make sure that the END
  287.     jumps into the correct position when RETURN is pressed. Finaly 
  288.     it will use the abbrev table to convert all REXX keywords into
  289.     upper case.
  290.  
  291.     
  292.     Example 2:
  293.     (setq rxdb-mode-hook '(lambda ()
  294.             (setq rxdb-command-name "/usr/local/bin/rexx")
  295.             ))
  296.  
  297.     is quite useable is UNIX environments.
  298.  
  299.  
  300.              KNOWN BUGS/PROBLEMS
  301.  
  302.     -- Nested comments aren't supported. This is because the standard
  303.     Emacs parsing functions are used. A new can be written in elisp but
  304.     I don't belive it will be efficient enough.
  305.  
  306.  
  307.     -- The Amigaport V1.26 of GNUEmacs has a annoying bug; it quotes
  308.     all arguments to commands, therefore RX can't be called directly.
  309.  
  310.     A workaround is to specify rexx-command-name to "rxnq", which
  311.     is a small (264 bytes!) command (i.e. hack) which strips the quotes
  312.     and calls RX. To do this, place the following line into the
  313.     rxdb-mode-hook is the s:.emacs file:
  314.  
  315.         (setq rxdb-command-name "rxnq")
  316.  
  317.     And place rxnq in the loadpath.
  318.  
  319.     Emacs 19 and 20 have since been ported to the Amiga and the above
  320.     fix may not be neccessary. Unfortunatley the start-process command
  321.     doesn't seem to work on my machine and I cannot run rexx-debug. 
  322.     Please contact me if you know more.
  323.  
  324.                  FINAL WORDS
  325.  
  326.     I would like to thank Bo Liljegren and Johan Bergkvist, both
  327.     members of Swedish User Group of Amiga (SUGA). A special
  328.     thank is also given to Malin, who has put up with me while
  329.     writing this, and other programs.
  330.  
  331.     Suggestions, new ideas and (positive) criticism are highly
  332.     appreciated. Please email them to:
  333.  
  334.         andersl@csd.uu.se
  335.  
  336.     or snail mail them to:
  337.  
  338.         Anders Lindgren
  339.         Kantorsg. 2-331
  340.         754 24 Uppsala
  341.         Sverige
  342.  
  343.                     /Anders Lindgren, 93-03-20
  344.  
  345.  
  346.                 FINAL WORDS II
  347.  
  348.     After having used rexx-mode for a year with or more on my Amiga
  349.     I felt I should release the updates I had made ie font-locking.
  350.     Having spoken to Anders (who used to use in on an Amiga    as well)
  351.     I decided to take over maintainance as I taught myself a reasonable
  352.     amount of elisp to be able to further improve the mode. So send your
  353.     comments to me at:
  354.  
  355.         james.perrin@man.ac.uk
  356.  
  357.     and check out the rexx-mode homepage at:
  358.  
  359.         http://www.man.ac.uk/MVC/general/staff/perrin/rexx.html
  360.  
  361.  
  362.     James S Perrin 29 April 2001
  363.